@colixsystems/widget-sdk 0.212.0 → 0.214.0

package/README.md

@@ -83,7 +83,60 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.212.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.214.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.214.0 (contract 1.173.0)
+
+**Who is behind a figure — `useActiveUsers({ within, group_id, limit, offset })`.** One page of the users seen within `within` — `"online"` (default; the app open in the last two minutes), `"day"` (since midnight in the workspace's time zone), `"week"` or `"month"` (the last 7 / 30 days) — most recently seen first, as `[{ id, name, last_active_at, last_platform }]` with `total` for paging. Same gate as `useUserActivity` (`users.activity:*` plus the "View user activity" permission); pass `null` to read nothing.
+
+**"Who joined" — `useUsers({ joined_since, sort: "newest" })`.** The admin user list narrows to users created since `joined_since` (a `YYYY-MM-DD` date read in the workspace's time zone, or an ISO instant) and lists them newest first. Join dates are admin data, so a caller with only the directory view gets the plain list.
+
+**Reminding several — `remind(id, message, { refetch: false })`.** `useInactiveUsers`' `remind` re-reads the page after each reminder; pass `{ refetch: false }` while sending a batch and call `refetch()` once at the end.
+
+### What's new in 0.213.0 (contract 1.172.0)
+
+**New component `<ConfirmDialog>` — the standard "are you sure?".** Widgets asked for confirmation each in their own way (a button that re-labels itself to be pressed twice, a hand-laid Yes / No row), so a delete looked and behaved differently from one widget to the next. `<ConfirmDialog>` is that prompt, built once as a preset of `<Modal>` and `<Button>`:
+
+```jsx
+import { useState } from "react";
+import { ConfirmDialog, Button, useToast } from "@colixsystems/widget-sdk";
+
+function DeleteOrder({ order, onDelete }) {
+  const [asking, setAsking] = useState(false);
+  const { showToast } = useToast();
+  return (
+    <>
+      <Button variant="danger" title="Delete" onPress={() => setAsking(true)} />
+      <ConfirmDialog
+        visible={asking}
+        tone="destructive"
+        title="Delete this order?"
+        message="This cannot be undone."
+        confirmLabel="Delete"
+        onCancel={() => setAsking(false)}
+        onConfirm={async () => {
+          try {
+            await onDelete(order.id);
+          } catch (err) {
+            showToast({ kind: "error", message: err.message });
+          }
+          setAsking(false);
+        }}
+      />
+    </>
+  );
+}
+```
+
+Props: `visible`, `title` (the question), `message` (what confirming does; text is drawn in the theme's body style, any other node as it is), `confirmLabel` and `cancelLabel`, `tone` (`default` | `destructive`), `busy`, `onConfirm`, `onCancel`, `closeAccessibilityLabel` and `testID` (the parts take `-message`, `-cancel`, `-confirm` and `-busy`, plus the Modal's own).
+
+- **Cancelling is the safe default.** The Cancel button, the close button, a backdrop press, Escape on web and the Android back button all fire `onCancel`, never `onConfirm`.
+- **`tone="destructive"`** draws the confirm button as the danger `<Button>`, so it takes its colours from the theme's `destructive` scope (Design > Components > Destructive), and on web opens with focus on Cancel. `default` draws the primary button and opens with focus on Confirm. Focus placement is web only.
+- **Busy.** Return the action's promise from `onConfirm` and the dialog stays busy until it settles: both buttons are disabled, a `<Spinner>` shows, nothing dismisses the dialog, and a second press is ignored. Pass `busy` yourself when the action runs elsewhere; the two combine. A rejected promise is **not** caught: handle the failure inside `onConfirm`, otherwise it is reported as an unhandled rejection. Either way the dialog becomes usable again.
+- **It never closes itself.** Set `visible` to false from `onCancel` and once the action is done.
+- **Labels follow the app's language.** Unset, the buttons read the app's shared `confirm`, `cancel` and `close` translations (the same ones `useI18n().t("cancel")` resolves), falling back to English. Prefer a `confirmLabel` that names the action: "Delete", "Remove", "Send".
+
+It adds no theme scope: the panel follows `modal`, the actions `button`, a destructive confirm `destructive`. `<Button>` now forwards a `ref` to its pressable, which is how the dialog places focus. Additive.
 
 ### What's new in 0.212.0 (contract 1.171.0)
 
@@ -201,7 +254,7 @@ Like the `loading` scope, `alert` styles an SDK component rather than a widget's
 
 **An app's user totals for its own admins — `useUserStats({ days, group_id })`.** Active and deactivated users, new users per day (7 / 30 days) or week (90 days) with the previous period's total beside them, users in no group, empty groups, and invite figures. Totals only — never a list of people. Needs `users.read:*` and the viewer's admin user access (else `error.code === "FORBIDDEN"`); `stats.invites` is null unless the widget also declares `users.write:*` and the viewer holds it.
 
-**User activity — `useUserActivity({ days, group_id })` and `useInactiveUsers({ inactive_days, group_id, limit, offset })`.** For a workspace that records user activity: who is online now, active in the last day / week / month, never active, active users per day or week, the web / iOS / Android split and the active share per group — and a page of the users not seen recently, never-seen first. Needs `users.activity:*` and the viewer's "View user activity" permission (else `error.code === "FORBIDDEN"`); when the workspace does not record activity, `error.reason === "ACTIVITY_DISABLED"` — show that, not zeros. Before user activity is offered to the workspace at all, `error.reason` is `"ACTIVITY_UNAVAILABLE"`: hide the section, as for `FORBIDDEN`. `useInactiveUsers` also returns `remind(userId, { title, body })`, which notifies one of them and records when (each row carries `last_reminded_at`). Days follow the workspace's time zone (`period.time_zone`).
+**User activity — `useUserActivity({ days, group_id })` and `useInactiveUsers({ inactive_days, group_id, limit, offset })`.** For a workspace that records user activity: who is online now, active in the last day / week / month, never active, active users per day or week, the web / iOS / Android split and the active share per group — and a page of the users not seen recently, never-seen first. Needs `users.activity:*` and the viewer's "View user activity" permission (else `error.code === "FORBIDDEN"`); when the workspace does not record activity, `error.reason === "ACTIVITY_DISABLED"` — show that, not zeros. Before user activity is offered to the workspace at all, `error.reason` is `"ACTIVITY_UNAVAILABLE"`: hide the section, as for `FORBIDDEN`. `useInactiveUsers` also returns `remind(userId, { title, body })`, which notifies one of them and records when (each row carries `last_reminded_at`); pass `{ refetch: false }` as a third argument when reminding several, then call `refetch()` once. Days follow the workspace's time zone (`period.time_zone`).
 
 **Linter fix.** A widget that uses `useGroups` or `useUsers` is no longer refused for a write it never makes: `StyleSheet.create(...)` and an event subscription's bare `remove()` (an `AppState` listener, say) are not user or group writes.
 
@@ -2550,6 +2603,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `Overlay` — the screen-level overlay (sc-6607). `<Overlay visible={!!preview} onRequestClose={() => setPreview(null)} size="full">…</Overlay>` renders its children OUTSIDE the widget's layout box on both hosts (web portals it to the document root, native uses the OS modal), so no clipping card, `ScrollView` or neighbouring widget can cut off a document/media preview, lightbox or confirm dialog — which absolute positioning inside the widget cannot achieve on either platform. Children stay in your own React tree, so state and hooks work normally. `onRequestClose` carries the backdrop press, Escape on web, and the Android back button; `size` is `sm` | `md` (default) | `lg` | `full`; the scrim, surface, radius, padding and elevation come from the workspace theme. An anchored dropdown still belongs inside your own root.
+- `ConfirmDialog` — the standard confirmation prompt, a preset of `Modal` and `Button`. `<ConfirmDialog visible={asking} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel="Delete" onCancel={() => setAsking(false)} onConfirm={removeOrder} />` asks before a delete or any other action that cannot be undone. Cancel, the close button, the backdrop, Escape and the Android back button fire `onCancel`; a promise returned from `onConfirm` keeps it busy (buttons disabled, a second press ignored) until it settles. Props: `visible`, `title`, `message`, `confirmLabel`, `cancelLabel`, `tone` (`default` | `destructive`), `busy`, `onConfirm`, `onCancel`, `closeAccessibilityLabel`, `testID`. Use it instead of building a confirmation from `Modal` yourself.
 - `Modal` — the standard dialog, built on `Overlay`. `<Modal visible={open} onRequestClose={() => setOpen(false)} title="Edit order" footer={<Button title="Save" onPress={save} />}>…</Modal>` draws a title, a close button, a body that scrolls when it is long and a footer action row laid out below it. Its background, corner radius, padding, scrim, shadow and title colour come from the theme's `modal` scope (Design > Components > Dialogs), so every dialog in an app matches. Props: `visible`, `onRequestClose`, `dismissible`, `title`, `footer`, `presentation` (`dialog` | `sheet`), `size` (`sm` | `md` | `lg` | `full`), `dismissOnBackdropPress`, `role`, `initialFocusRef`, `closeAccessibilityLabel`, `accessibilityLabel`, `testID`. Use it for every dialog instead of hand-building a header and an action row inside `Overlay`.
 - `RichText` — the formatted-content renderer (sc-6970). `<RichText value={post.body} />` parses the markdown subset (`**bold**`, `*italic*` / `_italic_`, `` `code` ``, `#`/`##`/`###` headings, `-`/`*` bullets, `1.` ordered items, one-line `![alt](src "large")` images) and renders it with SDK primitives, so formatted content reads the same in the web Player and the exported Expo app. `value` is markdown, NOT HTML — widgets have no `dangerouslySetInnerHTML` on either host, so tags in a content string render as literal tag soup; stored text that still holds legacy HTML is stripped to plain text rather than shown as markup. Props: `value`, `renderImage` (`({ src, alt, size }) => node` — supply it when images are filestore ids, because resolving one needs the scopes your own widget holds; without it only absolute `http(s)` URLs render), `style`, `testID`. Colour, type scale and leading come from the workspace theme — never re-style them.
 - `MarkdownInput` — the authoring half of `<RichText>` (sc-6970). `<MarkdownInput value={draft} onChange={setDraft} />` is a multi-line field, a toolbar whose buttons wrap the current SELECTION in markdown markers (bold, italic, code, H2, H3, bullets, numbered list, each toggling back off), and a live `<RichText>` preview of the result underneath — the way to let an app USER write formatted text, instead of a bare `TextInput` plus hand-rolled buttons that can only splice literal tags into the value. Props: `value`, `onChange(next)`, `placeholder`, `previewLabel` (default `Preview`), `showPreview` (default true), `renderImage` (passed through to the preview), `minHeight` (150) and `maxHeight` (280) so a long draft scrolls inside its box, `accessibilityLabel`, `style`, `testID`.

package/dist/button-view.js

@@ -100,8 +100,9 @@ export function makeButton(rn) {
    * @param {boolean} [props.hostThemed] — `fields` already carry the theme
    *   (a built-in the host folded); skip the second fold, which would add the
    *   Button widget's own scopes to a form submit or a Link action.
+   * @param {object} ref — forwarded to the pressable, so a caller can focus it.
    */
-  function Button({
+  const Button = React.forwardRef(function Button({
     title,
     variant = "primary",
     icon,
@@ -114,7 +115,7 @@ export function makeButton(rn) {
     hostThemed = false,
     accessibilityLabel,
     testID,
-  }) {
+  }, ref) {
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
     const { colors, spacing, radii, typography } = theme;
     const f = hostThemed
@@ -192,6 +193,7 @@ export function makeButton(rn) {
     return React.createElement(
       Pressable,
       {
+        ref,
         onPress,
         disabled,
         accessibilityRole: "button",
@@ -202,7 +204,7 @@ export function makeButton(rn) {
       },
       children,
     );
-  }
+  });
 
   Button.displayName = "Button";
   return Button;

package/dist/confirm-dialog-view.js

@@ -0,0 +1,158 @@
+// The ONE implementation behind the `<ConfirmDialog>` SDK component: a preset
+// of `<Modal>` holding a message, a Cancel and a Confirm `<Button>`.
+//
+// Bound per host by confirm-dialog.js / confirm-dialog.native.js, which differ
+// only in where the primitives come from, so the two hosts cannot drift.
+
+import React from "react";
+import { useHostSharedText, useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { textRoleStyle } from "./text-roles.js";
+
+function isThenable(value) {
+  return value != null && typeof value.then === "function";
+}
+
+function isText(value) {
+  return typeof value === "string" || typeof value === "number";
+}
+
+/**
+ * Bind the shared confirmation to one platform's primitives and to that
+ * host's `<Modal>`, `<Button>` and `<Spinner>`.
+ *
+ * @param {{Text: any}} rn
+ * @param {any} Modal — the host's bound `<Modal>`.
+ * @param {any} Button — the host's bound `<Button>`.
+ * @param {any} Spinner — the host's bound `<Spinner>`.
+ */
+export function makeConfirmDialog(rn, Modal, Button, Spinner) {
+  const { Text } = rn;
+
+  // Rendered inside the Modal, so it reads the theme the Modal re-inks.
+  function Message({ testID, children }) {
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    return React.createElement(
+      Text,
+      { testID, style: textRoleStyle("body", theme.typography, theme.colors) },
+      children,
+    );
+  }
+
+  /**
+   * The standard "are you sure?" prompt. Cancelling is the safe default: the
+   * close button, the backdrop, Escape (web) and the Android back button all
+   * fire `onCancel`, never `onConfirm`.
+   *
+   * @param {object} props
+   * @param {boolean} [props.visible] — nothing is mounted while false.
+   * @param {string} props.title — the question, e.g. "Delete this order?".
+   * @param {any} [props.message] — what confirming does; text is drawn in the
+   *   theme's body style, any other node is rendered as it is.
+   * @param {string} [props.confirmLabel] — default the app's "Confirm".
+   * @param {string} [props.cancelLabel] — default the app's "Cancel".
+   * @param {"default"|"destructive"} [props.tone] — `destructive` draws the
+   *   confirm button from the theme's Destructive colours and, on web, opens
+   *   with focus on Cancel; `default` opens with focus on Confirm.
+   * @param {boolean} [props.busy] — the confirmed action is running: both
+   *   buttons are disabled, a loading indicator shows, nothing closes it.
+   * @param {() => void|Promise<any>} [props.onConfirm] — a returned promise
+   *   keeps the dialog busy until it settles. A rejection is not caught.
+   * @param {() => void} [props.onCancel]
+   * @param {string} [props.closeAccessibilityLabel] — default the app's "Close".
+   * @param {string} [props.testID] — on the panel; the parts take `-message`,
+   *   `-cancel`, `-confirm` and `-busy`, plus the Modal's own.
+   */
+  function ConfirmDialog({
+    visible = false,
+    title,
+    message,
+    confirmLabel,
+    cancelLabel,
+    tone = "default",
+    busy = false,
+    onConfirm,
+    onCancel,
+    closeAccessibilityLabel,
+    testID,
+  }) {
+    const sharedConfirm = useHostSharedText("confirm", "Confirm");
+    const sharedCancel = useHostSharedText("cancel", "Cancel");
+    const sharedClose = useHostSharedText("close", "Close");
+    const [pending, setPending] = React.useState(false);
+    // Set before the re-render, so a second press in the same frame is ignored.
+    const inFlight = React.useRef(false);
+    const cancelRef = React.useRef(null);
+    const confirmRef = React.useRef(null);
+
+    const working = busy || pending;
+    const destructive = tone === "destructive";
+    const part = (name) => (testID ? `${testID}-${name}` : undefined);
+
+    const confirm = () => {
+      if (working || inFlight.current || typeof onConfirm !== "function") return;
+      const result = onConfirm();
+      if (!isThenable(result)) return;
+      inFlight.current = true;
+      setPending(true);
+      const settle = () => {
+        inFlight.current = false;
+        setPending(false);
+      };
+      result.then(settle, (error) => {
+        settle();
+        // Rethrown so a failure the caller did not handle is still reported.
+        throw error;
+      });
+    };
+
+    const cancel = () => {
+      if (working || inFlight.current) return;
+      if (typeof onCancel === "function") onCancel();
+    };
+
+    const footer = React.createElement(
+      React.Fragment,
+      null,
+      working ? React.createElement(Spinner, { testID: part("busy") }) : null,
+      React.createElement(Button, {
+        ref: cancelRef,
+        variant: "secondary",
+        title: cancelLabel ?? sharedCancel,
+        onPress: cancel,
+        disabled: working,
+        testID: part("cancel"),
+      }),
+      React.createElement(Button, {
+        ref: confirmRef,
+        variant: destructive ? "danger" : "primary",
+        title: confirmLabel ?? sharedConfirm,
+        onPress: confirm,
+        disabled: working,
+        testID: part("confirm"),
+      }),
+    );
+
+    return React.createElement(
+      Modal,
+      {
+        visible,
+        title,
+        footer,
+        role: "alertdialog",
+        size: "sm",
+        dismissible: !working,
+        onRequestClose: cancel,
+        initialFocusRef: destructive ? cancelRef : confirmRef,
+        closeAccessibilityLabel: closeAccessibilityLabel ?? sharedClose,
+        testID,
+      },
+      isText(message)
+        ? React.createElement(Message, { testID: part("message") }, message)
+        : message,
+    );
+  }
+
+  ConfirmDialog.displayName = "ConfirmDialog";
+  return ConfirmDialog;
+}

package/dist/confirm-dialog.js

@@ -0,0 +1,11 @@
+// `<ConfirmDialog>` (web). Binds ./confirm-dialog-view.js to react-native-web
+// and the web `<Modal>`, `<Button>` and `<Spinner>`; see ./primitives.js for
+// why not the bare specifier.
+
+import { Text } from "react-native-web";
+import { makeConfirmDialog } from "./confirm-dialog-view.js";
+import { Modal } from "./modal.js";
+import { Button } from "./button.js";
+import { Spinner } from "./loading.js";
+
+export const ConfirmDialog = makeConfirmDialog({ Text }, Modal, Button, Spinner);

package/dist/confirm-dialog.native.js

@@ -0,0 +1,11 @@
+// `<ConfirmDialog>` (native). Binds ./confirm-dialog-view.js to React Native's
+// own primitives and the native `<Modal>`, `<Button>` and `<Spinner>`; only the
+// imports differ from ./confirm-dialog.js.
+
+import { Text } from "react-native";
+import { makeConfirmDialog } from "./confirm-dialog-view.js";
+import { Modal } from "./modal.native.js";
+import { Button } from "./button.native.js";
+import { Spinner } from "./loading.native.js";
+
+export const ConfirmDialog = makeConfirmDialog({ Text }, Modal, Button, Spinner);

package/dist/contract.cjs

@@ -1960,7 +1960,9 @@ const HOOKS = [
       "Returns { users, loading, error, refetch, invite, deactivate, " +
       "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "res.data; rows are snake_case (is_active, created_at, …). For an admin, " +
+      "query { joined_since, sort: \"newest\" } lists who joined since a date " +
+      "(read in the workspace's time zone), newest first. Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
@@ -2082,6 +2084,30 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11066 — who was seen in a window, behind users.activity.
+  {
+    name: "useActiveUsers",
+    signature: "useActiveUsers({ within, group_id, limit, offset } | null)",
+    optionalArgs: ["within", "group_id", "limit", "offset"],
+    description:
+      "One page of users seen within `within`: \"online\" (default; the app " +
+      "open in the last two minutes), \"day\" (since midnight in the " +
+      "workspace's time zone), \"week\" or \"month\" (the last 7 / 30 days), " +
+      "most recently seen first: `users` = [{ id, name, last_active_at, " +
+      "last_platform }], `total` for paging. Use it to show WHO is behind an " +
+      "online or active figure. Same gate and errors as useUserActivity; null " +
+      "reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_platform }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   {
     name: "useInactiveUsers",
     signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
@@ -2091,7 +2117,8 @@ const HOOKS = [
       "never-seen first, then least recently seen: `users` = [{ id, name, " +
       "last_active_at, last_reminded_at }] (last_active_at null = never seen " +
       "since recording began), `total` for paging. `remind(id, { title, body })` " +
-      "notifies one of them, records when (last_reminded_at) and re-reads. " +
+      "notifies one of them, records when (last_reminded_at) and re-reads; " +
+      "pass `{ refetch: false }` third to skip the re-read in a batch. " +
       "Same gate and errors as useUserActivity; null reads nothing.",
     returnShape: {
       users: "Array<{ id, name, last_active_at, last_reminded_at }>",
@@ -2100,7 +2127,7 @@ const HOOKS = [
       fetching: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
-      remind: "(id, { title, body }) => Promise<void>",
+      remind: "(id, { title, body }, { refetch? }) => Promise<void>",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
@@ -2920,6 +2947,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "ConfirmDialog",
+    description:
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-8104 — the in-app emoji picker. Typed emoji always worked; what this
   // replaces is being forced out to the OS keyboard to find one.
   {
@@ -5628,7 +5662,16 @@ const CONTRACT = deepFreeze({
   //    switch, so an existing `<Switch>` with no colour props is repainted:
   //    its tracks follow the theme on both hosts and its "on" thumb is white
   //    on the web. A caller's `trackColor` / `thumbColor` still win.
-  version: "1.171.0",
+  // 1.172.0: additive (sc-10925) — the `ConfirmDialog` primitive: the standard
+  //    confirmation, a preset of `Modal` and `Button` (title, message, confirm
+  //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
+  //    theme scope: the panel reads `modal`, the actions `button` and
+  //    `destructive`. `Button` forwards a ref to its pressable.
+  // 1.173.0: additive (sc-11066) — `useActiveUsers(query)` lists who was
+  //    seen online / today / in 7 or 30 days through the new
+  //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
+  //    `sort: "newest"` for an admin's "who joined" list.
+  version: "1.173.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1960,7 +1960,9 @@ const HOOKS = [
       "Returns { users, loading, error, refetch, invite, deactivate, " +
       "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "res.data; rows are snake_case (is_active, created_at, …). For an admin, " +
+      "query { joined_since, sort: \"newest\" } lists who joined since a date " +
+      "(read in the workspace's time zone), newest first. Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
@@ -2082,6 +2084,30 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11066 — who was seen in a window, behind users.activity.
+  {
+    name: "useActiveUsers",
+    signature: "useActiveUsers({ within, group_id, limit, offset } | null)",
+    optionalArgs: ["within", "group_id", "limit", "offset"],
+    description:
+      "One page of users seen within `within`: \"online\" (default; the app " +
+      "open in the last two minutes), \"day\" (since midnight in the " +
+      "workspace's time zone), \"week\" or \"month\" (the last 7 / 30 days), " +
+      "most recently seen first: `users` = [{ id, name, last_active_at, " +
+      "last_platform }], `total` for paging. Use it to show WHO is behind an " +
+      "online or active figure. Same gate and errors as useUserActivity; null " +
+      "reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_platform }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   {
     name: "useInactiveUsers",
     signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
@@ -2091,7 +2117,8 @@ const HOOKS = [
       "never-seen first, then least recently seen: `users` = [{ id, name, " +
       "last_active_at, last_reminded_at }] (last_active_at null = never seen " +
       "since recording began), `total` for paging. `remind(id, { title, body })` " +
-      "notifies one of them, records when (last_reminded_at) and re-reads. " +
+      "notifies one of them, records when (last_reminded_at) and re-reads; " +
+      "pass `{ refetch: false }` third to skip the re-read in a batch. " +
       "Same gate and errors as useUserActivity; null reads nothing.",
     returnShape: {
       users: "Array<{ id, name, last_active_at, last_reminded_at }>",
@@ -2100,7 +2127,7 @@ const HOOKS = [
       fetching: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
-      remind: "(id, { title, body }) => Promise<void>",
+      remind: "(id, { title, body }, { refetch? }) => Promise<void>",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
@@ -2920,6 +2947,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "ConfirmDialog",
+    description:
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-8104 — the in-app emoji picker. Typed emoji always worked; what this
   // replaces is being forced out to the OS keyboard to find one.
   {
@@ -5624,7 +5658,16 @@ const CONTRACT = deepFreeze({
   //    switch, so an existing `<Switch>` with no colour props is repainted:
   //    its tracks follow the theme on both hosts and its "on" thumb is white
   //    on the web. A caller's `trackColor` / `thumbColor` still win.
-  version: "1.171.0",
+  // 1.172.0: additive (sc-10925) — the `ConfirmDialog` primitive: the standard
+  //    confirmation, a preset of `Modal` and `Button` (title, message, confirm
+  //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
+  //    theme scope: the panel reads `modal`, the actions `button` and
+  //    `destructive`. `Button` forwards a ref to its pressable.
+  // 1.173.0: additive (sc-11066) — `useActiveUsers(query)` lists who was
+  //    seen online / today / in 7 or 30 days through the new
+  //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
+  //    `sort: "newest"` for an admin's "who joined" list.
+  version: "1.173.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -1107,6 +1107,21 @@ export function useUserActivity(query?: { days?: 7 | 30 | 90; group_id?: string
   refetch(): Promise<void>;
 };
 
+/** Users seen within `within` (default "online"), most recently seen first. */
+export function useActiveUsers(query?: {
+  within?: "online" | "day" | "week" | "month";
+  group_id?: string;
+  limit?: number;
+  offset?: number;
+} | null): {
+  users: Array<{ id: string; name: string; last_active_at: string; last_platform: "web" | "ios" | "android" | "unknown" }>;
+  total: number | null;
+  loading: boolean;
+  fetching: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+};
+
 /** Users not seen for `inactive_days` (default 30), never-seen first. */
 export function useInactiveUsers(query?: {
   inactive_days?: number;
@@ -1121,7 +1136,8 @@ export function useInactiveUsers(query?: {
   error: Error | null;
   refetch(): Promise<void>;
   /** Notify one user, record when, then re-read the page. */
-  remind(id: string, message: { title: string; body: string }): Promise<void>;
+  /** `{ refetch: false }` skips re-reading the page, for a batch that reads once. */
+  remind(id: string, message: { title: string; body: string }, options?: { refetch?: boolean }): Promise<void>;
 };
 
 /** One record's online members, as `useOnlineMembers` reports them. */
@@ -2743,6 +2759,12 @@ export interface UsersQuery {
   is_active?: boolean;
   /** Restrict to members of one app-user group — the `id` of a `useGroups()` row. */
   group_id?: string;
+  /** Admin view only: users created since this date (workspace time zone) or instant. */
+  joined_since?: string;
+  /** Admin view only: "newest" lists the most recently created first. */
+  sort?: "name" | "newest";
+  /** "real" leaves out preview and store-review accounts; an in-app admin always gets "real". */
+  audience?: "all" | "real" | "preview";
   limit?: number;
   offset?: number;
 }
@@ -3360,6 +3382,70 @@ export const Modal: (props: {
   children?: ReactNode;
 }) => any;
 
+export type ConfirmDialogTone = "default" | "destructive";
+
+/**
+ * The standard confirmation prompt: a preset of `<Modal>` with a message, a
+ * Cancel and a Confirm `<Button>`. Use it before a delete or any other action
+ * that cannot be undone, so every confirmation in the app looks and behaves
+ * the same. Cancelling is the safe default: the Cancel button, the close
+ * button, the backdrop, Escape (web) and the Android back button all fire
+ * `onCancel`, never `onConfirm`.
+ *
+ * It adds no theme scope: the panel follows `modal`, the actions `button`,
+ * and a destructive confirm the `destructive` scope. It never closes itself;
+ * set `visible` false from `onCancel` and once the action is done.
+ *
+ * @example
+ *   <ConfirmDialog
+ *     visible={!!pending}
+ *     tone="destructive"
+ *     title="Delete this order?"
+ *     message="This cannot be undone."
+ *     confirmLabel="Delete"
+ *     onCancel={() => setPending(null)}
+ *     onConfirm={async () => {
+ *       await remove(pending.id);
+ *       setPending(null);
+ *     }}
+ *   />
+ */
+export const ConfirmDialog: (props: {
+  /** Nothing renders (and nothing is mounted) while this is false. */
+  visible?: boolean;
+  /** The question, e.g. "Delete this order?". */
+  title: string;
+  /** What confirming does. Text is drawn in the theme's body style. */
+  message?: ReactNode;
+  /** Defaults to the app's translated "Confirm". Name the action instead. */
+  confirmLabel?: string;
+  /** Defaults to the app's translated "Cancel". */
+  cancelLabel?: string;
+  /**
+   * `destructive` draws the confirm button from the theme's Destructive
+   * colours and, on web, opens with focus on Cancel. `default` opens with
+   * focus on Confirm. Focus placement is web only.
+   */
+  tone?: ConfirmDialogTone;
+  /**
+   * The confirmed action is running: both buttons are disabled, a loading
+   * indicator shows, and the backdrop, Escape and Android back do nothing.
+   */
+  busy?: boolean;
+  /**
+   * Return the action's promise and the dialog stays busy until it settles,
+   * ignoring a second press. A rejection is not caught: handle the failure
+   * here, or it is reported as an unhandled rejection.
+   */
+  onConfirm?: () => void | Promise<unknown>;
+  /** The Cancel and close buttons, backdrop, Escape (web) and Android back. */
+  onCancel?: () => void;
+  /** Label for the close button. Defaults to the app's translated "Close". */
+  closeAccessibilityLabel?: string;
+  /** On the panel; the parts take `-message`, `-cancel`, `-confirm` and `-busy`. */
+  testID?: string;
+}) => any;
+
 /** Per-list row overrides; unset values follow Theme Settings > Lists. */
 export interface ListRowTokens {
   rowPadding?: number;
@@ -3616,6 +3702,8 @@ export const Button: (props: {
   labelStyle?: any;
   accessibilityLabel?: string;
   testID?: string;
+  /** Forwarded to the pressable, so you can focus the button. */
+  ref?: { current: any } | ((node: any) => void);
 }) => any;
 
 /**

package/dist/index.js

@@ -127,6 +127,7 @@ export { useDatastoreFigure } from "./datastore-figure.js";
 export {
   useUserStats,
   useUserActivity,
+  useActiveUsers,
   useInactiveUsers,
 } from "./stats-hooks.js";
 // sc-11025 — one source, bound to how each platform says the app is in front.
@@ -282,6 +283,8 @@ export { Spinner, Skeleton } from "./loading.js";
 export { Banner } from "./banner.js";
 // The standard dialog, on `<Overlay>`; follows the theme's `modal` scope.
 export { Modal } from "./modal.js";
+// The standard confirmation, a preset of `<Modal>` and `<Button>`.
+export { ConfirmDialog } from "./confirm-dialog.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/index.native.js

@@ -125,6 +125,7 @@ export { useDatastoreFigure } from "./datastore-figure.js";
 export {
   useUserStats,
   useUserActivity,
+  useActiveUsers,
   useInactiveUsers,
 } from "./stats-hooks.js";
 // sc-11025 — see the note on the web mirror in ./index.js.
@@ -275,6 +276,8 @@ export { Spinner, Skeleton } from "./loading.native.js";
 export { Banner } from "./banner.native.js";
 // The standard dialog, on `<Overlay>`; follows the theme's `modal` scope.
 export { Modal } from "./modal.native.js";
+// The standard confirmation, a preset of `<Modal>` and `<Button>`.
+export { ConfirmDialog } from "./confirm-dialog.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/stats-hooks.js

@@ -108,13 +108,32 @@ export function useUserActivity(query) {
   return { ...state, activity: data };
 }
 
+/**
+ * sc-11066 — one page of users seen within `within` ("online" — the last two
+ * minutes — "day", "week" or "month"), most recently seen first. `query`:
+ * `{ within?, group_id?, limit?, offset? }`. Returns `{ users, total, loading,
+ * fetching, error, refetch }`; each user is `{ id, name, last_active_at,
+ * last_platform }`. Same gate as useUserActivity; null reads nothing.
+ */
+export function useActiveUsers(query) {
+  const users = useUsersNamespace("useActiveUsers", "active");
+  const key = query === null ? null : serialize(query);
+  const { data, ...state } = useKeyedRead(() => users.active(query), "active-users", key, toDirectoryError);
+  return {
+    ...state,
+    users: data && Array.isArray(data.data) ? data.data : [],
+    total: data && data.meta && Number.isFinite(data.meta.total) ? data.meta.total : null,
+  };
+}
+
 /**
  * sc-10691 — one page of users not seen for `inactive_days` (default 30),
  * never-seen first. `query`: `{ inactive_days?, group_id?, limit?, offset? }`.
  * Returns `{ users, total, loading, fetching, error, refetch, remind }`; each
  * user is `{ id, name, last_active_at, last_reminded_at }` (last_active_at
  * null when never seen). `remind(id, { title, body })` notifies one and
- * re-reads the page. Same gate as useUserActivity.
+ * re-reads the page; `{ refetch: false }` as a third argument skips the
+ * re-read, so a batch reads once at the end. Same gate as useUserActivity.
  */
 export function useInactiveUsers(query) {
   const users = useUsersNamespace("useInactiveUsers", "inactive");
@@ -122,7 +141,7 @@ export function useInactiveUsers(query) {
   const { data, ...state } = useKeyedRead(() => users.inactive(query), "inactive", key, toDirectoryError);
   const { refetch } = state;
   const remind = useCallback(
-    async (id, message) => {
+    async (id, message, { refetch: reread = true } = {}) => {
       if (typeof users.remind !== "function") {
         throw new Error("useInactiveUsers: host did not inject ctx.directory.users.remind");
       }
@@ -131,7 +150,7 @@ export function useInactiveUsers(query) {
       } catch (err) {
         throw toDirectoryError(err);
       }
-      await refetch();
+      if (reread) await refetch();
     },
     [users, refetch],
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.212.0",
+  "version": "0.214.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -1960,7 +1960,9 @@ const HOOKS = [
       "Returns { users, loading, error, refetch, invite, deactivate, " +
       "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "res.data; rows are snake_case (is_active, created_at, …). For an admin, " +
+      "query { joined_since, sort: \"newest\" } lists who joined since a date " +
+      "(read in the workspace's time zone), newest first. Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
@@ -2082,6 +2084,30 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11066 — who was seen in a window, behind users.activity.
+  {
+    name: "useActiveUsers",
+    signature: "useActiveUsers({ within, group_id, limit, offset } | null)",
+    optionalArgs: ["within", "group_id", "limit", "offset"],
+    description:
+      "One page of users seen within `within`: \"online\" (default; the app " +
+      "open in the last two minutes), \"day\" (since midnight in the " +
+      "workspace's time zone), \"week\" or \"month\" (the last 7 / 30 days), " +
+      "most recently seen first: `users` = [{ id, name, last_active_at, " +
+      "last_platform }], `total` for paging. Use it to show WHO is behind an " +
+      "online or active figure. Same gate and errors as useUserActivity; null " +
+      "reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_platform }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   {
     name: "useInactiveUsers",
     signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
@@ -2091,7 +2117,8 @@ const HOOKS = [
       "never-seen first, then least recently seen: `users` = [{ id, name, " +
       "last_active_at, last_reminded_at }] (last_active_at null = never seen " +
       "since recording began), `total` for paging. `remind(id, { title, body })` " +
-      "notifies one of them, records when (last_reminded_at) and re-reads. " +
+      "notifies one of them, records when (last_reminded_at) and re-reads; " +
+      "pass `{ refetch: false }` third to skip the re-read in a batch. " +
       "Same gate and errors as useUserActivity; null reads nothing.",
     returnShape: {
       users: "Array<{ id, name, last_active_at, last_reminded_at }>",
@@ -2100,7 +2127,7 @@ const HOOKS = [
       fetching: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
-      remind: "(id, { title, body }) => Promise<void>",
+      remind: "(id, { title, body }, { refetch? }) => Promise<void>",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
@@ -2920,6 +2947,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "ConfirmDialog",
+    description:
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-8104 — the in-app emoji picker. Typed emoji always worked; what this
   // replaces is being forced out to the OS keyboard to find one.
   {
@@ -5624,7 +5658,16 @@ const CONTRACT = deepFreeze({
   //    switch, so an existing `<Switch>` with no colour props is repainted:
   //    its tracks follow the theme on both hosts and its "on" thumb is white
   //    on the web. A caller's `trackColor` / `thumbColor` still win.
-  version: "1.171.0",
+  // 1.172.0: additive (sc-10925) — the `ConfirmDialog` primitive: the standard
+  //    confirmation, a preset of `Modal` and `Button` (title, message, confirm
+  //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
+  //    theme scope: the panel reads `modal`, the actions `button` and
+  //    `destructive`. `Button` forwards a ref to its pressable.
+  // 1.173.0: additive (sc-11066) — `useActiveUsers(query)` lists who was
+  //    seen online / today / in 7 or 30 days through the new
+  //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
+  //    `sort: "newest"` for an admin's "who joined" list.
+  version: "1.173.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,